CHAPTER 9 : Resource Bundle Editor |
In order to allow the text in your application (button labels etc.) to be easily translated for other language users, you will need to define resource bundles. Instead of entering a string label for a Button or Label component in the Property Sheet, a key is used. Keys can then be linked to strings in any number of languages by using the Resource Bundle Editor.
The Resource Bundle Editor, shown in Figure 9-1, is displayed when you open a Resource Bundle save file, select "New Resource Bundle" from the Class Editor File menu, double-click over a Resource Bundle save file in the Visaj project window or when you press the "New Resource Bundle" button on the project window toolbar.
The Resource Bundle Editor is arranged as a table, with one column per language and one key per line. To add a string into the table, select the table cell and enter the string into the text field at the top of the window. Press the Return key to put the string into the selected cell. When a cell is selected, the locale of the text field is set to match the language of that cell. If your system supports that language, you will be able to type using characters of the selected language.
The File menu in the Resource Bundle Editor contains items to import and export text as well as the standard file operations for opening, closing and saving files.
"Import language" and "Export language" operate on one language at a time, using the currently selected language only.
The export command provides a means of listing all keys, in the currently selected language, which require translation. When "Export language..." is selected from the File menu, a dialog appears prompting you for a character encoding for the export file. This is provided so that you can be sure the file you are exporting can be read by whoever will be reading the file. Different languages require different encodings and, indeed, different editors will expect different encodings too. A scrolling list of all commonly used character encodings is provided. Simply select one of these and press "OK". Once you have specified the encoding, the Resource Bundle Editor prompts you for the name of the file to be exported.
The exported file contains one line for each key. Each line is of the format:
<key>=<value>
Note - Only the currently selected language is exported. If you have nothing selected, nothing is exported.
The selected encoding is saved with the selected language so that you can import back into the same language later.
The import commands allow you to read in newly translated data. There is a pullright menu, available from the "Import language" item in the File menu, which allows you to choose whether the imported data should merge with or append to the data already present.
Import operates on the currently selected language only. Make sure that you select the correct language before importing.
Each language is exported using a specified character encoding. The Resource Bundle Editor remembers which encoding was used. If, however, you are not using the same save file which was used for the export command, you will be prompted for the character encoding which was used to export the language initially.
Once it has found the correct character encoding to use, the Resource Bundle Editor prompts you for the name of the file to be imported.
The Resource Bundle Editor expects an import file to have one line for each key. Each line must be of the format:
<key>=<value>
Note - The Resource Bundle Editor imports into the currently selected language. If there is no language selected, nothing is imported.
When a Resource Bundle is saved, the table is serialized into the specified file. By convention, Visaj expects Resource Bundle save files to have the filename extension "vrb". When a file with such an extension is opened, Visaj will automatically open it in the Resource Bundle Editor.
The Edit menu contains Cut, Copy, Paste, Clear, Undo and Redo. These apply to the text in a cell. There are also some extra items allowing you to add and delete languages and keys (which correspond to columns and rows in the table).
To add new languages to the Resource Bundle Editor, select "Add language..." from the Edit menu. A dialog appears which asks for the new language and country, as shown in Figure 9-2.
There is a small arrow button next to each of these which, when pressed, displays a popup menu containing those languages or countries which are known to Java. When a selection is made from one of these popup menus, the two-letter ISO Language Code (ISO-639) (or two-letter ISO Country Code (ISO-3166)) is displayed in the text area. You may enter these codes directly if you wish. You do not have to enter the country code, but if you do the Resource Bundle Editor tries to find an appropriate flag to display in the table. This is for display purposes only.
If you wish to see a list of the language and country codes, try the following web sites:
http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt (for the ISO Language Codes)
http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html (for the ISO Country Codes)
To add new keys to your Resource Bundle Editor, press the "new Key" button on the toolbar or choose "Add key" from the Edit menu. A new, blank line appears at the bottom of the table.
The Generate menu contains two items: "Generate all files" and "Set properties...". The former item generates a class file for each of the languages in the table - including the default. The filenames of these generated files are constructed by using the class name followed by the two letter ISO code for the language and the two letter ISO code for the country, if provided. The language and country codes are preceded by the under bar (_) character. The "Default" is given no language or country code. Subclassing occurs as follows:
The filename is always given the ".java" suffix. The example resource bundle shown in Figure 9-1 contains the French language of the country France. Assuming the class name is "Greetings", the class file for that language would be:
GreetingsResourceBundle_fr_FR.java
Here is the contents of that file:
/*
** French (France) resource bundle for Greetings
*/
public class GreetingsResourceBundle_fr_FR extends
GreetingsResourceBundle {
public Object[][] getContents() {
return contents;
}
static final Object[][] contents = {
{"Yes", "Oui"},
{"No", "Non"},
{"Hello", "Bonjour"},
};
}
The first time you generate code, you will be prompted for a class name and package name. You do not have to provide a package or the generated files, but you are required to provide a class name. This is also used as the filename of the generated code file. If you wish to change the class or package name before generating again, choose "Set properties..." from the Generate menu.
You may create resource bundles using the Resource Bundle Editor, save them and generate the appropriate class files. In order to use them in the Class Editor you will have to do two things:
1. | Set a Code Expression for the String property. |
2. | Add the resource bundle to the class in the Class Editor. |
You will need to use code expressions in order to make the generated code read the value from the resource bundle. To do this:
1. | Select the component in the containment hierarchy which has a String property. |
A Button or Label, for example. |
2. | Display the Property Sheet and select the "text" property. |
3. | Choose "Code expression" from the option menu at the bottom of the Property Sheet. |
4. | Type the following into the Code expression text box: |
resources.getString("key")
where "resources" is the variable name of the resource bundle and "key" is the key in the resource bundle. Remember to type Return at the end of the line. |
To add a resource bundle to a class which is using its keys, do the following:
1. | In the Class Editor, select the ResourceBundle object from the palette. |
2. | This appears in the invisible beans area. |
3. | Change the variable name of the resource bundle to the class name you provided in the Resource Bundle Editor. |
4. | Display the Property Sheet for the resource bundle and change the Object Initialization property to use the code expression: |
ResourceBundle.getBundle("ClassName")
where "ClassName" is the name of the class you have generated. |
Resources fetched from a resource bundle do not affect the dynamic display. They do display correctly when the generated code is run.